/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.model.events;

/**
 * <p>This is a subclass of XREEvent that represents keyboard events. It defines some properties specific to these
 * events. Note that values of all custom properties are actually stored in the XREEvent#params map.</p>
 *
 * <p><strong>Thread safety:</strong> This class is mutable and not thread safe.</p>
 *
 * @author saarixx, jmn
 * @version 1.0
 */
@SuppressWarnings("boxing")
public class XREKeyboardEvent extends XREViewEvent {

    /**
     * <p>Represents the name of the "on key up" event.</p>
     *
     * <p>This is a string constant used by the user when setting the name of the event.</p>
     */
    public static final String ON_KEY_UP_EVENT_NAME = "onKeyUp";

    /**
     * <p>Represents the name of the "on key down" event.</p>
     *
     * <p>This is a string constant used by the user when setting the name of the event.</p>
     */
    public static final String ON_KEY_DOWN_EVENT_NAME = "onKeyDown";

    /**
     * <p>Represents the name of the "on key start repeating" event.</p>
     *
     * <p>This is a string constant used by the user when setting the name of the event.</p>
     */
    public static final String ON_KEY_START_REPEATING_EVENT_NAME = "onKeyStartRepeating";

    /**
     * <p>Represents the name of the "on key up" preview event.</p>
     *
     * <p>This is a string constant used by the user when setting the name of the event.</p>
     */
    public static final String ON_PREVIEW_KEY_UP_EVENT_NAME = "onPreviewKeyUp";

    /**
     * <p>Represents the name of the "on key down" preview event.</p>
     *
     * <p>This is a string constant used by the user when setting the name of the event.</p>
     */
    public static final String ON_PREVIEW_KEY_DOWN_EVENT_NAME = "onPreviewKeyDown";

    /**
     * <p>Represents the name of the "on key start repeating" preview event.</p>
     *
     * <p>This is a string constant used by the user when setting the name of the event.</p>
     */
    public static final String ON_PREVIEW_KEY_START_REPEATING_EVENT_NAME = "onPreviewKeyStartRepeating";

    /**
     * <p>Represents the name used to retrieve the virtual key code parameter.</p>
     */
    private static final String VIRTUAL_KEY_CODE = "virtualKeyCode";

    /**
     * <p>Represents the name used to retrieve the raw code parameter.</p>
     */
    private static final String RAW_CODE = "rawCode";

    /**
     * <p>Represents the name used to retrieve the alt parameter.</p>
     */
    private static final String ALT = "alt";

    /**
     * <p>Represents the name used to retrieve the control parameter.</p>
     */
    private static final String CONTROL = "control";

    /**
     * <p>Represents the name used to retrieve the shift parameter.</p>
     */
    private static final String SHIFT = "shift";

    /**
     * <p>Represents the name used to retrieve the meta parameter.</p>
     */
    private static final String META = "meta";

    /**
     * <p>Creates new instance of {@link XREKeyboardEvent} class.</p>
     */
    public XREKeyboardEvent() {
        // empty constructor
    }

    /**
     * <p>Retrieves the virtual key code corresponding to the key pressed.</p>
     *
     * @return the virtual key code corresponding to the key pressed
     *
     * @throws IllegalStateException if the requested parameter has wrong type in the parameters map or params is null
     */
    public XREVirtualKeyCode getVirtualKeyCode() {
        return getTypedParam(VIRTUAL_KEY_CODE, XREVirtualKeyCode.class);
    }

    /**
     * <p>Sets the virtual key code corresponding to the key pressed.</p>
     *
     * @param virtualKeyCode the virtual key code corresponding to the key pressed
     *
     * @throws IllegalStateException if params is null
     */
    public void setVirtualKeyCode(XREVirtualKeyCode virtualKeyCode) {
        setParam(VIRTUAL_KEY_CODE, virtualKeyCode);
    }

    /**
     * <p>Retrieves the raw code for the key as reported by the device.</p>
     *
     * @return the raw code for the key as reported by the device
     *
     * @throws IllegalStateException if the requested parameter has wrong type in the parameters map or params is null
     */
    public int getRawCode() {
        return getTypedParam(RAW_CODE, Integer.class);
    }

    /**
     * <p>Sets the raw code for the key as reported by the device.</p>
     *
     * @param rawCode the raw code for the key as reported by the device
     *
     * @throws IllegalStateException if params is null
     */
    public void setRawCode(int rawCode) {
        setParam(RAW_CODE, rawCode);
    }

    /**
     * <p>Retrieves the value that indicates whether alt key was down at the time of the event.</p>
     *
     * @return the value that indicates whether alt key was down at the time of the event
     *
     * @throws IllegalStateException if the requested parameter has wrong type in the parameters map or params is null
     */
    public boolean isAlt() {
        return getTypedParam(ALT, Boolean.class);
    }

    /**
     * <p>Sets the value that indicates whether alt key was down at the time of the event.</p>
     *
     * @param alt the value that indicates whether alt key was down at the time of the event
     *
     * @throws IllegalStateException if params is null
     */
    public void setAlt(boolean alt) {
        setParam(ALT, alt);
    }

    /**
     * <p>Retrieves the value that indicates whether control key was down at the time of the event.</p>
     *
     * @return the value that indicates whether control key was down at the time of the event
     *
     * @throws IllegalStateException if the requested parameter has wrong type in the parameters map or params is null
     */
    public boolean isControl() {
        return getTypedParam(CONTROL, Boolean.class);
    }

    /**
     * <p>Sets the value that indicates whether control key was down at the time of the event.</p>
     *
     * @param control the value that indicates whether control key was down at the time of the event
     *
     * @throws IllegalStateException if params is null
     */
    public void setControl(boolean control) {
        setParam(CONTROL, control);
    }

    /**
     * <p>Retrieves the value that indicates whether shift key was down at the time of the event.</p>
     *
     * @return the value that indicates whether shift key was down at the time of the event
     *
     * @throws IllegalStateException if the requested parameter has wrong type in the parameters map or params is null
     */
    public boolean isShift() {
        return getTypedParam(SHIFT, Boolean.class);
    }

    /**
     * <p>Sets the value that indicates whether shift key was down at the time of the event.</p>
     *
     * @param shift the value that indicates whether shift key was down at the time of the event
     *
     * @throws IllegalStateException if params is null
     */
    public void setShift(boolean shift) {
        setParam(SHIFT, shift);
    }

    /**
     * <p>Retrieves the value that indicates whether meta key was down at the time of the event.</p>
     *
     * @return the value that indicates whether meta key was down at the time of the event
     *
     * @throws IllegalStateException if the requested parameter has wrong type in the parameters map or params is null
     */
    public boolean isMeta() {
        return getTypedParam(META, Boolean.class);
    }

    /**
     * <p>Sets the value that indicates whether meta key was down at the time of the event.</p>
     *
     * @param meta the value that indicates whether meta key was down at the time of the event
     *
     * @throws IllegalStateException if params is null
     */
    public void setMeta(boolean meta) {
        setParam(META, meta);
    }
}

